home *** CD-ROM | disk | FTP | other *** search
/ Spidla DivX / DivX.bin / FLAC 1.1.0 / include / FLAC / format.h < prev    next >
Encoding:
C/C++ Source or Header  |  2003-01-14  |  29.3 KB  |  798 lines
  1. /* libFLAC - Free Lossless Audio Codec library
  2.  * Copyright (C) 2000,2001,2002,2003  Josh Coalson
  3.  *
  4.  * This library is free software; you can redistribute it and/or
  5.  * modify it under the terms of the GNU Library General Public
  6.  * License as published by the Free Software Foundation; either
  7.  * version 2 of the License, or (at your option) any later version.
  8.  *
  9.  * This library is distributed in the hope that it will be useful,
  10.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.  * Library General Public License for more details.
  13.  *
  14.  * You should have received a copy of the GNU Library General Public
  15.  * License along with this library; if not, write to the
  16.  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17.  * Boston, MA  02111-1307, USA.
  18.  */
  19.  
  20. #ifndef FLAC__FORMAT_H
  21. #define FLAC__FORMAT_H
  22.  
  23. #include "export.h"
  24. #include "ordinals.h"
  25.  
  26. #ifdef __cplusplus
  27. extern "C" {
  28. #endif
  29.  
  30. /** \file include/FLAC/format.h
  31.  *
  32.  *  \brief
  33.  *  This module contains structure definitions for the representation
  34.  *  of FLAC format components in memory.  These are the basic
  35.  *  structures used by the rest of the interfaces.
  36.  *
  37.  *  See the detailed documentation in the
  38.  *  \link flac_format format \endlink module.
  39.  */
  40.  
  41. /** \defgroup flac_format FLAC/format.h: format components
  42.  *  \ingroup flac
  43.  *
  44.  *  \brief
  45.  *  This module contains structure definitions for the representation
  46.  *  of FLAC format components in memory.  These are the basic
  47.  *  structures used by the rest of the interfaces.
  48.  *
  49.  *  First, you should be familiar with the
  50.  *  <A HREF="../format.html">FLAC format</A>.  Many of the values here
  51.  *  follow directly from the specification.  As a user of libFLAC, the
  52.  *  interesting parts really are the structures that describe the frame
  53.  *  header and metadata blocks.
  54.  *
  55.  *  The format structures here are very primitive, designed to store
  56.  *  information in an efficient way.  Reading information from the
  57.  *  structures is easy but creating or modifying them directly is
  58.  *  more complex.  For the most part, as a user of a library, editing
  59.  *  is not necessary; however, for metadata blocks it is, so there are
  60.  *  convenience functions provided in the \link flac_metadata metadata
  61.  *  module \endlink to simplify the manipulation of metadata blocks.
  62.  *
  63.  * \note
  64.  * It's not the best convention, but symbols ending in _LEN are in bits
  65.  * and _LENGTH are in bytes.  _LENGTH symbols are \#defines instead of
  66.  * global variables because they are usually used when declaring byte
  67.  * arrays and some compilers require compile-time knowledge of array
  68.  * sizes when declared on the stack.
  69.  *
  70.  * \{
  71.  */
  72.  
  73.  
  74. /*
  75.     Most of the values described in this file are defined by the FLAC
  76.     format specification.  There is nothing to tune here.
  77. */
  78.  
  79. /** The minimum block size, in samples, permitted by the format. */
  80. #define FLAC__MIN_BLOCK_SIZE (16u)
  81.  
  82. /** The maximum block size, in samples, permitted by the format. */
  83. #define FLAC__MAX_BLOCK_SIZE (65535u)
  84.  
  85. /** The maximum number of channels permitted by the format. */
  86. #define FLAC__MAX_CHANNELS (8u)
  87.  
  88. /** The minimum sample resolution permitted by the format. */
  89. #define FLAC__MIN_BITS_PER_SAMPLE (4u)
  90.  
  91. /** The maximum sample resolution permitted by the format. */
  92. #define FLAC__MAX_BITS_PER_SAMPLE (32u)
  93.  
  94. /** The maximum sample resolution permitted by libFLAC.
  95.  *
  96.  * \warning
  97.  * FLAC__MAX_BITS_PER_SAMPLE is the limit of the FLAC format.  However,
  98.  * the reference encoder/decoder is currently limited to 24 bits because
  99.  * of prevalent 32-bit math, so make sure and use this value when
  100.  * appropriate.
  101.  */
  102. #define FLAC__REFERENCE_CODEC_MAX_BITS_PER_SAMPLE (24u)
  103.  
  104. /** The maximum sample rate permitted by the format.  The value is
  105.  *  ((2 ^ 16) - 1) * 10; see <A HREF="../format.html">FLAC format</A>
  106.  *  as to why.
  107.  */
  108. #define FLAC__MAX_SAMPLE_RATE (655350u)
  109.  
  110. /** The maximum LPC order permitted by the format. */
  111. #define FLAC__MAX_LPC_ORDER (32u)
  112.  
  113. /** The minimum quantized linear predictor coefficient precision
  114.  *  permitted by the format.
  115.  */
  116. #define FLAC__MIN_QLP_COEFF_PRECISION (5u)
  117.  
  118. /** The maximum quantized linear predictor coefficient precision
  119.  *  permitted by the format.
  120.  */
  121. #define FLAC__MAX_QLP_COEFF_PRECISION (15u)
  122.  
  123. /** The maximum order of the fixed predictors permitted by the format. */
  124. #define FLAC__MAX_FIXED_ORDER (4u)
  125.  
  126. /** The maximum Rice partition order permitted by the format. */
  127. #define FLAC__MAX_RICE_PARTITION_ORDER (15u)
  128.  
  129. /** The maximum Rice partition order permitted by the FLAC Subset. */
  130. #define FLAC__SUBSET_MAX_RICE_PARTITION_ORDER (8u)
  131.  
  132. /** The version string of the release, stamped onto the libraries and binaries.
  133.  *
  134.  * \note
  135.  * This does not correspond to the shared library version number, which
  136.  * is used to determine binary compatibility.
  137.  */
  138. extern FLAC_API const char *FLAC__VERSION_STRING;
  139.  
  140. /** The vendor string inserted by the encoder into the VORBIS_COMMENT block.
  141.  *  This is a nulL-terminated ASCII string; when inserted into the
  142.  *  VORBIS_COMMENT the trailing null is stripped.
  143.  */
  144. extern FLAC_API const char *FLAC__VENDOR_STRING;
  145.  
  146. /** The byte string representation of the beginning of a FLAC stream. */
  147. extern FLAC_API const FLAC__byte FLAC__STREAM_SYNC_STRING[4]; /* = "fLaC" */
  148.  
  149. /** The 32-bit integer big-endian representation of the beginning of
  150.  *  a FLAC stream.
  151.  */
  152. extern FLAC_API const unsigned FLAC__STREAM_SYNC; /* = 0x664C6143 */
  153.  
  154. /** The length of the FLAC signature in bits. */
  155. extern FLAC_API const unsigned FLAC__STREAM_SYNC_LEN; /* = 32 bits */
  156.  
  157. /** The length of the FLAC signature in bytes. */
  158. #define FLAC__STREAM_SYNC_LENGTH (4u)
  159.  
  160.  
  161. /*****************************************************************************
  162.  *
  163.  * Subframe structures
  164.  *
  165.  *****************************************************************************/
  166.  
  167. /*****************************************************************************/
  168.  
  169. /** An enumeration of the available entropy coding methods. */
  170. typedef enum {
  171.     FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE = 0
  172.     /**< Residual is coded by partitioning into contexts, each with it's own
  173.      * Rice parameter. */
  174. } FLAC__EntropyCodingMethodType;
  175.  
  176. /** Maps a FLAC__EntropyCodingMethodType to a C string.
  177.  *
  178.  *  Using a FLAC__EntropyCodingMethodType as the index to this array will
  179.  *  give the string equivalent.  The contents should not be modified.
  180.  */
  181. extern FLAC_API const char * const FLAC__EntropyCodingMethodTypeString[];
  182.  
  183.  
  184. /** Contents of a Rice partitioned residual
  185.  */
  186. typedef struct {
  187.  
  188.     unsigned *parameters;
  189.     /**< The Rice parameters for each context. */
  190.  
  191.     unsigned *raw_bits;
  192.     /**< Widths for escape-coded partitions. */
  193.  
  194.     unsigned capacity_by_order;
  195.     /**< The capacity of the \a parameters and \a raw_bits arrays
  196.      * specified as an order, i.e. the number of array elements
  197.      * allocated is 2 ^ \a capacity_by_order.
  198.      */
  199. } FLAC__EntropyCodingMethod_PartitionedRiceContents;
  200.  
  201. /** Header for a Rice partitioned residual.  (c.f. <A HREF="../format.html#partitioned_rice">format specification</A>)
  202.  */
  203. typedef struct {
  204.  
  205.     unsigned order;
  206.     /**< The partition order, i.e. # of contexts = 2 ^ \a order. */
  207.  
  208.     const FLAC__EntropyCodingMethod_PartitionedRiceContents *contents;
  209.     /**< The context's Rice parameters and/or raw bits. */
  210.  
  211. } FLAC__EntropyCodingMethod_PartitionedRice;
  212.  
  213. extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ORDER_LEN; /**< == 4 (bits) */
  214. extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN; /**< == 4 (bits) */
  215. extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_RAW_LEN; /**< == 5 (bits) */
  216.  
  217. extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_ESCAPE_PARAMETER;
  218. /**< == (1<<FLAC__ENTROPY_CODING_METHOD_PARTITIONED_RICE_PARAMETER_LEN)-1 */
  219.  
  220. /** Header for the entropy coding method.  (c.f. <A HREF="../format.html#residual">format specification</A>)
  221.  */
  222. typedef struct {
  223.     FLAC__EntropyCodingMethodType type;
  224.     union {
  225.         FLAC__EntropyCodingMethod_PartitionedRice partitioned_rice;
  226.     } data;
  227. } FLAC__EntropyCodingMethod;
  228.  
  229. extern FLAC_API const unsigned FLAC__ENTROPY_CODING_METHOD_TYPE_LEN; /**< == 2 (bits) */
  230.  
  231. /*****************************************************************************/
  232.  
  233. /** An enumeration of the available subframe types. */
  234. typedef enum {
  235.     FLAC__SUBFRAME_TYPE_CONSTANT = 0, /**< constant signal */
  236.     FLAC__SUBFRAME_TYPE_VERBATIM = 1, /**< uncompressed signal */
  237.     FLAC__SUBFRAME_TYPE_FIXED = 2, /**< fixed polynomial prediction */
  238.     FLAC__SUBFRAME_TYPE_LPC = 3 /**< linear prediction */
  239. } FLAC__SubframeType;
  240.  
  241. /** Maps a FLAC__SubframeType to a C string.
  242.  *
  243.  *  Using a FLAC__SubframeType as the index to this array will
  244.  *  give the string equivalent.  The contents should not be modified.
  245.  */
  246. extern FLAC_API const char * const FLAC__SubframeTypeString[];
  247.  
  248.  
  249. /** CONSTANT subframe.  (c.f. <A HREF="../format.html#subframe_constant">format specification</A>)
  250.  */
  251. typedef struct {
  252.     FLAC__int32 value; /**< The constant signal value. */
  253. } FLAC__Subframe_Constant;
  254.  
  255.  
  256. /** VERBATIM subframe.  (c.f. <A HREF="../format.html#subframe_verbatim">format specification</A>)
  257.  */
  258. typedef struct {
  259.     const FLAC__int32 *data; /**< A pointer to verbatim signal. */
  260. } FLAC__Subframe_Verbatim;
  261.  
  262.  
  263. /** FIXED subframe.  (c.f. <A HREF="../format.html#subframe_fixed">format specification</A>)
  264.  */
  265. typedef struct {
  266.     FLAC__EntropyCodingMethod entropy_coding_method;
  267.     /**< The residual coding method. */
  268.  
  269.     unsigned order;
  270.     /**< The polynomial order. */
  271.  
  272.     FLAC__int32 warmup[FLAC__MAX_FIXED_ORDER];
  273.     /**< Warmup samples to prime the predictor, length == order. */
  274.  
  275.     const FLAC__int32 *residual;
  276.     /**< The residual signal, length == (blocksize minus order) samples. */
  277. } FLAC__Subframe_Fixed;
  278.  
  279.  
  280. /** LPC subframe.  (c.f. <A HREF="../format.html#subframe_lpc">format specification</A>)
  281.  */
  282. typedef struct {
  283.     FLAC__EntropyCodingMethod entropy_coding_method;
  284.     /**< The residual coding method. */
  285.  
  286.     unsigned order;
  287.     /**< The FIR order. */
  288.  
  289.     unsigned qlp_coeff_precision;
  290.     /**< Quantized FIR filter coefficient precision in bits. */
  291.  
  292.     int quantization_level;
  293.     /**< The qlp coeff shift needed. */
  294.  
  295.     FLAC__int32 qlp_coeff[FLAC__MAX_LPC_ORDER];
  296.     /**< FIR filter coefficients. */
  297.  
  298.     FLAC__int32 warmup[FLAC__MAX_LPC_ORDER];
  299.     /**< Warmup samples to prime the predictor, length == order. */
  300.  
  301.     const FLAC__int32 *residual;
  302.     /**< The residual signal, length == (blocksize minus order) samples. */
  303. } FLAC__Subframe_LPC;
  304.  
  305. extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_COEFF_PRECISION_LEN; /**< == 4 (bits) */
  306. extern FLAC_API const unsigned FLAC__SUBFRAME_LPC_QLP_SHIFT_LEN; /**< == 5 (bits) */
  307.  
  308.  
  309. /** FLAC subframe structure.  (c.f. <A HREF="../format.html#subframe">format specification</A>)
  310.  */
  311. typedef struct {
  312.     FLAC__SubframeType type;
  313.     union {
  314.         FLAC__Subframe_Constant constant;
  315.         FLAC__Subframe_Fixed fixed;
  316.         FLAC__Subframe_LPC lpc;
  317.         FLAC__Subframe_Verbatim verbatim;
  318.     } data;
  319.     unsigned wasted_bits;
  320. } FLAC__Subframe;
  321.  
  322. extern FLAC_API const unsigned FLAC__SUBFRAME_ZERO_PAD_LEN; /**< == 1 (bit) */
  323. extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LEN; /**< == 6 (bits) */
  324. extern FLAC_API const unsigned FLAC__SUBFRAME_WASTED_BITS_FLAG_LEN; /**< == 1 (bit) */
  325.  
  326. extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_CONSTANT_BYTE_ALIGNED_MASK; /* = 0x00 */
  327. extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_VERBATIM_BYTE_ALIGNED_MASK; /* = 0x02 */
  328. extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_FIXED_BYTE_ALIGNED_MASK; /* = 0x10 */
  329. extern FLAC_API const unsigned FLAC__SUBFRAME_TYPE_LPC_BYTE_ALIGNED_MASK; /* = 0x40 */
  330.  
  331. /*****************************************************************************/
  332.  
  333.  
  334. /*****************************************************************************
  335.  *
  336.  * Frame structures
  337.  *
  338.  *****************************************************************************/
  339.  
  340. /** An enumeration of the available channel assignments. */
  341. typedef enum {
  342.     FLAC__CHANNEL_ASSIGNMENT_INDEPENDENT = 0, /**< independent channels */
  343.     FLAC__CHANNEL_ASSIGNMENT_LEFT_SIDE = 1, /**< left+side stereo */
  344.     FLAC__CHANNEL_ASSIGNMENT_RIGHT_SIDE = 2, /**< right+side stereo */
  345.     FLAC__CHANNEL_ASSIGNMENT_MID_SIDE = 3 /**< mid+side stereo */
  346. } FLAC__ChannelAssignment;
  347.  
  348. /** Maps a FLAC__ChannelAssignment to a C string.
  349.  *
  350.  *  Using a FLAC__ChannelAssignment as the index to this array will
  351.  *  give the string equivalent.  The contents should not be modified.
  352.  */
  353. extern FLAC_API const char * const FLAC__ChannelAssignmentString[];
  354.  
  355. /** An enumeration of the possible frame numbering methods. */
  356. typedef enum {
  357.     FLAC__FRAME_NUMBER_TYPE_FRAME_NUMBER, /**< number contains the frame number */
  358.     FLAC__FRAME_NUMBER_TYPE_SAMPLE_NUMBER /**< number contains the sample number of first sample in frame */
  359. } FLAC__FrameNumberType;
  360.  
  361. /** Maps a FLAC__FrameNumberType to a C string.
  362.  *
  363.  *  Using a FLAC__FrameNumberType as the index to this array will
  364.  *  give the string equivalent.  The contents should not be modified.
  365.  */
  366. extern FLAC_API const char * const FLAC__FrameNumberTypeString[];
  367.  
  368.  
  369. /** FLAC frame header structure.  (c.f. <A HREF="../format.html#frame_header">format specification</A>)
  370.  */
  371. typedef struct {
  372.     unsigned blocksize;
  373.     /**< The number of samples per subframe. */
  374.  
  375.     unsigned sample_rate;
  376.     /**< The sample rate in Hz. */
  377.  
  378.     unsigned channels;
  379.     /**< The number of channels (== number of subframes). */
  380.  
  381.     FLAC__ChannelAssignment channel_assignment;
  382.     /**< The channel assignment for the frame. */
  383.  
  384.     unsigned bits_per_sample;
  385.     /**< The sample resolution. */
  386.  
  387.     FLAC__FrameNumberType number_type;
  388.     /**< The numbering scheme used for the frame. */
  389.  
  390.     union {
  391.         FLAC__uint32 frame_number;
  392.         FLAC__uint64 sample_number;
  393.     } number;
  394.     /**< The frame number or sample number of first sample in frame;
  395.      * use the \a number_type value to determine which to use. */
  396.  
  397.     FLAC__uint8 crc;
  398.     /**< CRC-8 (polynomial = x^8 + x^2 + x^1 + x^0, initialized with 0)
  399.      * of the raw frame header bytes, meaning everything before the CRC byte
  400.      * including the sync code.
  401.      */
  402. } FLAC__FrameHeader;
  403.  
  404. extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC; /**< == 0x3ffe; the frame header sync code */
  405. extern FLAC_API const unsigned FLAC__FRAME_HEADER_SYNC_LEN; /**< == 14 (bits) */
  406. extern FLAC_API const unsigned FLAC__FRAME_HEADER_RESERVED_LEN; /**< == 2 (bits) */
  407. extern FLAC_API const unsigned FLAC__FRAME_HEADER_BLOCK_SIZE_LEN; /**< == 4 (bits) */
  408. extern FLAC_API const unsigned FLAC__FRAME_HEADER_SAMPLE_RATE_LEN; /**< == 4 (bits) */
  409. extern FLAC_API const unsigned FLAC__FRAME_HEADER_CHANNEL_ASSIGNMENT_LEN; /**< == 4 (bits) */
  410. extern FLAC_API const unsigned FLAC__FRAME_HEADER_BITS_PER_SAMPLE_LEN; /**< == 3 (bits) */
  411. extern FLAC_API const unsigned FLAC__FRAME_HEADER_ZERO_PAD_LEN; /**< == 1 (bit) */
  412. extern FLAC_API const unsigned FLAC__FRAME_HEADER_CRC_LEN; /**< == 8 (bits) */
  413.  
  414.  
  415. /** FLAC frame footer structure.  (c.f. <A HREF="../format.html#frame_footer">format specification</A>)
  416.  */
  417. typedef struct {
  418.     FLAC__uint16 crc;
  419.     /**< CRC-16 (polynomial = x^16 + x^15 + x^2 + x^0, initialized with
  420.      * 0) of the bytes before the crc, back to and including the frame header
  421.      * sync code.
  422.      */
  423. } FLAC__FrameFooter;
  424.  
  425. extern FLAC_API const unsigned FLAC__FRAME_FOOTER_CRC_LEN; /**< == 16 (bits) */
  426.  
  427.  
  428. /** FLAC frame structure.  (c.f. <A HREF="../format.html#frame">format specification</A>)
  429.  */
  430. typedef struct {
  431.     FLAC__FrameHeader header;
  432.     FLAC__Subframe subframes[FLAC__MAX_CHANNELS];
  433.     FLAC__FrameFooter footer;
  434. } FLAC__Frame;
  435.  
  436. /*****************************************************************************/
  437.  
  438.  
  439. /*****************************************************************************
  440.  *
  441.  * Meta-data structures
  442.  *
  443.  *****************************************************************************/
  444.  
  445. /** An enumeration of the available metadata block types. */
  446. typedef enum {
  447.  
  448.     FLAC__METADATA_TYPE_STREAMINFO = 0,
  449.     /**< <A HREF="../format.html#metadata_block_streaminfo">STREAMINFO</A> block */
  450.  
  451.     FLAC__METADATA_TYPE_PADDING = 1,
  452.     /**< <A HREF="../format.html#metadata_block_padding">PADDING</A> block */
  453.  
  454.     FLAC__METADATA_TYPE_APPLICATION = 2,
  455.     /**< <A HREF="../format.html#metadata_block_application">APPLICATION</A> block */
  456.  
  457.     FLAC__METADATA_TYPE_SEEKTABLE = 3,
  458.     /**< <A HREF="../format.html#metadata_block_seektable">SEEKTABLE</A> block */
  459.  
  460.     FLAC__METADATA_TYPE_VORBIS_COMMENT = 4,
  461.     /**< <A HREF="../format.html#metadata_block_vorbis_comment">VORBISCOMMENT</A> block */
  462.  
  463.     FLAC__METADATA_TYPE_CUESHEET = 5,
  464.     /**< <A HREF="../format.html#metadata_block_cuesheet">CUESHEET</A> block */
  465.  
  466.     FLAC__METADATA_TYPE_UNDEFINED = 6
  467.     /**< marker to denote beginning of undefined type range; this number will increase as new metadata types are added */
  468.  
  469. } FLAC__MetadataType;
  470.  
  471. /** Maps a FLAC__MetadataType to a C string.
  472.  *
  473.  *  Using a FLAC__MetadataType as the index to this array will
  474.  *  give the string equivalent.  The contents should not be modified.
  475.  */
  476. extern FLAC_API const char * const FLAC__MetadataTypeString[];
  477.  
  478.  
  479. /** FLAC STREAMINFO structure.  (c.f. <A HREF="../format.html#metadata_block_streaminfo">format specification</A>)
  480.  */
  481. typedef struct {
  482.     unsigned min_blocksize, max_blocksize;
  483.     unsigned min_framesize, max_framesize;
  484.     unsigned sample_rate;
  485.     unsigned channels;
  486.     unsigned bits_per_sample;
  487.     FLAC__uint64 total_samples;
  488.     FLAC__byte md5sum[16];
  489. } FLAC__StreamMetadata_StreamInfo;
  490.  
  491. extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_BLOCK_SIZE_LEN; /**< == 16 (bits) */
  492. extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_BLOCK_SIZE_LEN; /**< == 16 (bits) */
  493. extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MIN_FRAME_SIZE_LEN; /**< == 24 (bits) */
  494. extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MAX_FRAME_SIZE_LEN; /**< == 24 (bits) */
  495. extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_SAMPLE_RATE_LEN; /**< == 20 (bits) */
  496. extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_CHANNELS_LEN; /**< == 3 (bits) */
  497. extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_BITS_PER_SAMPLE_LEN; /**< == 5 (bits) */
  498. extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_TOTAL_SAMPLES_LEN; /**< == 36 (bits) */
  499. extern FLAC_API const unsigned FLAC__STREAM_METADATA_STREAMINFO_MD5SUM_LEN; /**< == 128 (bits) */
  500.  
  501. /** The total stream length of the STREAMINFO block in bytes. */
  502. #define FLAC__STREAM_METADATA_STREAMINFO_LENGTH (34u)
  503.  
  504. /** FLAC PADDING structure.  (c.f. <A HREF="../format.html#metadata_block_padding">format specification</A>)
  505.  */
  506. typedef struct {
  507.     int dummy;
  508.     /**< Conceptually this is an empty struct since we don't store the
  509.      * padding bytes.  Empty structs are not allowed by some C compilers,
  510.      * hence the dummy.
  511.      */
  512. } FLAC__StreamMetadata_Padding;
  513.  
  514.  
  515. /** FLAC APPLICATION structure.  (c.f. <A HREF="../format.html#metadata_block_application">format specification</A>)
  516.  */
  517. typedef struct {
  518.     FLAC__byte id[4];
  519.     FLAC__byte *data;
  520. } FLAC__StreamMetadata_Application;
  521.  
  522. extern FLAC_API const unsigned FLAC__STREAM_METADATA_APPLICATION_ID_LEN; /**< == 32 (bits) */
  523.  
  524. /** SeekPoint structure used in SEEKTABLE blocks.  (c.f. <A HREF="../format.html#seekpoint">format specification</A>)
  525.  */
  526. typedef struct {
  527.     FLAC__uint64 sample_number;
  528.     /**<  The sample number of the target frame. */
  529.  
  530.     FLAC__uint64 stream_offset;
  531.     /**< The offset, in bytes, of the target frame with respect to
  532.      * beginning of the first frame. */
  533.  
  534.     unsigned frame_samples;
  535.     /**< The number of samples in the target frame. */
  536. } FLAC__StreamMetadata_SeekPoint;
  537.  
  538. extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_SAMPLE_NUMBER_LEN; /**< == 64 (bits) */
  539. extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_STREAM_OFFSET_LEN; /**< == 64 (bits) */
  540. extern FLAC_API const unsigned FLAC__STREAM_METADATA_SEEKPOINT_FRAME_SAMPLES_LEN; /**< == 16 (bits) */
  541.  
  542. /** The total stream length of a seek point in bytes. */
  543. #define FLAC__STREAM_METADATA_SEEKPOINT_LENGTH (18u)
  544.  
  545. /** The value used in the \a sample_number field of
  546.  *  FLAC__StreamMetadataSeekPoint used to indicate a placeholder
  547.  *  point (== 0xffffffffffffffff).
  548.  */
  549. extern FLAC_API const FLAC__uint64 FLAC__STREAM_METADATA_SEEKPOINT_PLACEHOLDER;
  550.  
  551.  
  552. /** FLAC SEEKTABLE structure.  (c.f. <A HREF="../format.html#metadata_block_seektable">format specification</A>)
  553.  *
  554.  * \note From the format specification:
  555.  * - The seek points must be sorted by ascending sample number.
  556.  * - Each seek point's sample number must be the first sample of the
  557.  *   target frame.
  558.  * - Each seek point's sample number must be unique within the table.
  559.  * - Existence of a SEEKTABLE block implies a correct setting of
  560.  *   total_samples in the stream_info block.
  561.  * - Behavior is undefined when more than one SEEKTABLE block is
  562.  *   present in a stream.
  563.  */
  564. typedef struct {
  565.     unsigned num_points;
  566.     FLAC__StreamMetadata_SeekPoint *points;
  567. } FLAC__StreamMetadata_SeekTable;
  568.  
  569.  
  570. /** Vorbis comment entry structure used in VORBIS_COMMENT blocks.  (c.f. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>)
  571.  */
  572. typedef struct {
  573.     FLAC__uint32 length;
  574.     FLAC__byte *entry;
  575. } FLAC__StreamMetadata_VorbisComment_Entry;
  576.  
  577. extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_ENTRY_LENGTH_LEN; /**< == 32 (bits) */
  578.  
  579.  
  580. /** FLAC VORBIS_COMMENT structure.  (c.f. <A HREF="../format.html#metadata_block_vorbis_comment">format specification</A>)
  581.  */
  582. typedef struct {
  583.     FLAC__StreamMetadata_VorbisComment_Entry vendor_string;
  584.     FLAC__uint32 num_comments;
  585.     FLAC__StreamMetadata_VorbisComment_Entry *comments;
  586. } FLAC__StreamMetadata_VorbisComment;
  587.  
  588. extern FLAC_API const unsigned FLAC__STREAM_METADATA_VORBIS_COMMENT_NUM_COMMENTS_LEN; /**< == 32 (bits) */
  589.  
  590.  
  591. /** FLAC CUESHEET track index structure.  (See the
  592.  * <A HREF="../format.html#cuesheet_track_index">format specification</A> for
  593.  * the full description of each field.)
  594.  */
  595. typedef struct {
  596.     FLAC__uint64 offset;
  597.     /**< Offset in samples, relative to the track offset, of the index
  598.      * point.
  599.      */
  600.  
  601.     FLAC__byte number;
  602.     /**< The index point number. */
  603. } FLAC__StreamMetadata_CueSheet_Index;
  604.  
  605. extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_OFFSET_LEN; /**< == 64 (bits) */
  606. extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_NUMBER_LEN; /**< == 8 (bits) */
  607. extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_INDEX_RESERVED_LEN; /**< == 3*8 (bits) */
  608.  
  609.  
  610. /** FLAC CUESHEET track structure.  (See the
  611.  * <A HREF="../format.html#cuesheet_track">format specification</A> for
  612.  * the full description of each field.)
  613.  */
  614. typedef struct {
  615.     FLAC__uint64 offset;
  616.     /**< Track offset in samples, relative to the beginning of the FLAC audio stream. */
  617.  
  618.     FLAC__byte number;
  619.     /**< The track number. */
  620.  
  621.     char isrc[13];
  622.     /**< Track ISRC.  This is a 12-digit alphanumeric code plus a trailing '\0' */
  623.  
  624.     unsigned type:1;
  625.     /**< The track type: 0 for audio, 1 for non-audio. */
  626.  
  627.     unsigned pre_emphasis:1;
  628.     /**< The pre-emphasis flag: 0 for no pre-emphasis, 1 for pre-emphasis. */
  629.  
  630.     FLAC__byte num_indices;
  631.     /**< The number of track index points. */
  632.  
  633.     FLAC__StreamMetadata_CueSheet_Index *indices;
  634.     /**< NULL if num_indices == 0, else pointer to array of index points. */
  635.  
  636. } FLAC__StreamMetadata_CueSheet_Track;
  637.  
  638. extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_OFFSET_LEN; /**< == 64 (bits) */
  639. extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUMBER_LEN; /**< == 8 (bits) */
  640. extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_ISRC_LEN; /**< == 12*8 (bits) */
  641. extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_TYPE_LEN; /**< == 1 (bit) */
  642. extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_PRE_EMPHASIS_LEN; /**< == 1 (bit) */
  643. extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_RESERVED_LEN; /**< == 6+13*8 (bits) */
  644. extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_TRACK_NUM_INDICES_LEN; /**< == 8 (bits) */
  645.  
  646.  
  647. /** FLAC CUESHEET structure.  (See the
  648.  * <A HREF="../format.html#metadata_block_cuesheet">format specification</A>
  649.  * for the full description of each field.)
  650.  */
  651. typedef struct {
  652.     char media_catalog_number[129];
  653.     /**< Media catalog number, in ASCII printable characters 0x20-0x7e.  In
  654.      * general, the media catalog number may be 0 to 128 bytes long; any
  655.      * unused characters should be right-padded with NUL characters.
  656.      */
  657.  
  658.     FLAC__uint64 lead_in;
  659.     /**< The number of lead-in samples. */
  660.  
  661.     FLAC__bool is_cd;
  662.     /**< \c true if CUESHEET corresponds to a Compact Disc, else \c false */
  663.  
  664.     unsigned num_tracks;
  665.     /**< The number of tracks. */
  666.  
  667.     FLAC__StreamMetadata_CueSheet_Track *tracks;
  668.     /**< NULL if num_tracks == 0, else pointer to array of tracks. */
  669.  
  670. } FLAC__StreamMetadata_CueSheet;
  671.  
  672. extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_MEDIA_CATALOG_NUMBER_LEN; /**< == 128*8 (bits) */
  673. extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_LEAD_IN_LEN; /**< == 64 (bits) */
  674. extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_IS_CD_LEN; /**< == 1 (bit) */
  675. extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_RESERVED_LEN; /**< == 7+258*8 (bits) */
  676. extern FLAC_API const unsigned FLAC__STREAM_METADATA_CUESHEET_NUM_TRACKS_LEN; /**< == 8 (bits) */
  677.  
  678.  
  679. /** Structure that is used when a metadata block of unknown type is loaded.
  680.  *  The contents are opaque.  The structure is used only internally to
  681.  *  correctly handle unknown metadata.
  682.  */
  683. typedef struct {
  684.     FLAC__byte *data;
  685. } FLAC__StreamMetadata_Unknown;
  686.  
  687.  
  688. /** FLAC metadata block structure.  (c.f. <A HREF="../format.html#metadata_block">format specification</A>)
  689.  */
  690. typedef struct {
  691.     FLAC__MetadataType type;
  692.     /**< The type of the metadata block; used determine which member of the
  693.      * \a data union to dereference.  If type >= FLAC__METADATA_TYPE_UNDEFINED
  694.      * then \a data.unknown must be used. */
  695.  
  696.     FLAC__bool is_last;
  697.     /**< \c true if this metadata block is the last, else \a false */
  698.  
  699.     unsigned length;
  700.     /**< Length, in bytes, of the block data as it appears in the stream. */
  701.  
  702.     union {
  703.         FLAC__StreamMetadata_StreamInfo stream_info;
  704.         FLAC__StreamMetadata_Padding padding;
  705.         FLAC__StreamMetadata_Application application;
  706.         FLAC__StreamMetadata_SeekTable seek_table;
  707.         FLAC__StreamMetadata_VorbisComment vorbis_comment;
  708.         FLAC__StreamMetadata_CueSheet cue_sheet;
  709.         FLAC__StreamMetadata_Unknown unknown;
  710.     } data;
  711.     /**< Polymorphic block data; use the \a type value to determine which
  712.      * to use. */
  713. } FLAC__StreamMetadata;
  714.  
  715. extern FLAC_API const unsigned FLAC__STREAM_METADATA_IS_LAST_LEN; /**< == 1 (bit) */
  716. extern FLAC_API const unsigned FLAC__STREAM_METADATA_TYPE_LEN; /**< == 7 (bits) */
  717. extern FLAC_API const unsigned FLAC__STREAM_METADATA_LENGTH_LEN; /**< == 24 (bits) */
  718.  
  719. /** The total stream length of a metadata block header in bytes. */
  720. #define FLAC__STREAM_METADATA_HEADER_LENGTH (4u)
  721.  
  722. /*****************************************************************************/
  723.  
  724.  
  725. /*****************************************************************************
  726.  *
  727.  * Utility functions
  728.  *
  729.  *****************************************************************************/
  730.  
  731. /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
  732. /** Tests that a sample rate is valid for FLAC.  Since the rules for valid
  733.  *  sample rates are slightly complex, they are encapsulated in this function.
  734.  *
  735.  * \param sample_rate  The sample rate to test for compliance.
  736.  * \retval FLAC__bool
  737.  *    \c true if the given sample rate conforms to the specification, else
  738.  *    \c false.
  739.  */
  740. FLAC_API FLAC__bool FLAC__format_sample_rate_is_valid(unsigned sample_rate);
  741.  
  742. /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
  743. /** Check a seek table to see if it conforms to the FLAC specification.
  744.  *  See the format specification for limits on the contents of the
  745.  *  seek table.
  746.  *
  747.  * \param seek_table  A pointer to a seek table to be checked.
  748.  * \assert
  749.  *    \code seek_table != NULL \endcode
  750.  * \retval FLAC__bool
  751.  *    \c false if seek table is illegal, else \c true.
  752.  */
  753. FLAC_API FLAC__bool FLAC__format_seektable_is_legal(const FLAC__StreamMetadata_SeekTable *seek_table);
  754.  
  755. /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
  756. /** Sort a seek table's seek points according to the format specification.
  757.  *  This includes a "unique-ification" step to remove duplicates, i.e.
  758.  *  seek points with identical \a sample_number values.  Duplicate seek
  759.  *  points are converted into placeholder points and sorted to the end of
  760.  *  the table.
  761.  *
  762.  * \param seek_table  A pointer to a seek table to be sorted.
  763.  * \assert
  764.  *    \code seek_table != NULL \endcode
  765.  * \retval unsigned
  766.  *    The number of duplicate seek points converted into placeholders.
  767.  */
  768. FLAC_API unsigned FLAC__format_seektable_sort(FLAC__StreamMetadata_SeekTable *seek_table);
  769.  
  770. /* @@@@ add to unit tests; it is already indirectly tested by the metadata_object tests */
  771. /** Check a cue sheet to see if it conforms to the FLAC specification.
  772.  *  See the format specification for limits on the contents of the
  773.  *  cue sheet.
  774.  *
  775.  * \param cue_sheet  A pointer to an existing cue sheet to be checked.
  776.  * \param check_cd_da_subset  If \c true, check CUESHEET against more
  777.  *                   stringent requirements for a CD-DA (audio) disc.
  778.  * \param violation  Address of a pointer to a string.  If there is a
  779.  *                   violation, a pointer to a string explanation of the
  780.  *                   violation will be returned here. \a violation may be
  781.  *                   \c NULL if you don't need the returned string.  Do not
  782.  *                   free the returned string; it will always point to static
  783.  *                   data.
  784.  * \assert
  785.  *    \code cue_sheet != NULL \endcode
  786.  * \retval FLAC__bool
  787.  *    \c false if cue sheet is illegal, else \c true.
  788.  */
  789. FLAC_API FLAC__bool FLAC__format_cuesheet_is_legal(const FLAC__StreamMetadata_CueSheet *cue_sheet, FLAC__bool check_cd_da_subset, const char **violation);
  790.  
  791. /* \} */
  792.  
  793. #ifdef __cplusplus
  794. }
  795. #endif
  796.  
  797. #endif
  798.